home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Libris Britannia 4
/
science library(b).zip
/
science library(b)
/
UTILITIE
/
CONVERSI
/
1396.ZIP
/
ALTERN22.DOC
< prev
next >
Wrap
Text File
|
1988-12-02
|
16KB
|
346 lines
ALTERN VERSION 2.2
ALTERNATE AND GLOBAL REPLACEMENT PROGRAM
By C.R.J. Currie
PURPOSE .............................................1
PREPARATION..........................................2
FORMAT OF STRING-LIST FILES..........................3
a) Lists for Alternate Replacement...............3
b) Lists for Global Replacement..................3
FORMAT OF FILE-LIST FILE.............................4
PARAGRAPH MARKER FILES...............................4
RUNNING ALTERN.......................................4
RUNNING THE FILEMAKE PROGRAM.........................5
LIMITATIONS..........................................6
HISTORY..............................................7
SOFTWARE LICENCE.....................................8
Altern v.2.2 documentation (c) C.R.J. Currie 1988 p. 1
ALTERN VERSION 2.2
ALTERNATE AND GLOBAL REPLACEMENT PROGRAM
By C.R.J. Currie
1. PURPOSE
ALTERN is a utility which helps to convert text files to
different formats or to prepare them for input to a
typesetter or output to a printer which your text editor
cannot drive. It allows the global replacement of every
string in a prepared list, or the alternate replacement of
paired strings. The last function is essential to convert
files prepared with a text editor such as Wordstar, which
uses 'toggles' to change text emphasis or type size, to a
format which requires that each style or size be overtly
specified.
Most text editors cannot cope with alternate
replacement, with bulk replacement of a series of strings at
once, or with automatic replacement throughout a set of
files. Some cannot even replace their own control codes.
ALTERN can do all that. It doesn't change your original
file, but makes a modified copy with the extension .COD.
For example a single run could replace every occurrence
of GOAT by ELEPHANT, every carriage return by a linefeed
with the 8th bit set, every odd-numbered occurrence of CAT
by DOG, and every even-numbered occurrence of CAT by SHEEP,
in each one of 100 files.
ALTERN uses single-character input and processes text a
paragraph at at time. The default paragraph marker is the
carriage return -- linefeed sequence (0D0A hex), but files
in formats which use other markers can be read and written.
ALTERN can also search e.g. Wordstar files for strings
in which some bytes may or may not have the eighth bit set,
and replace them. Version 2.2 cannot search independently
of case: REAGAN and Reagan are treated as different strings.
Altern v.2.2 documentation (c) C.R.J. Currie 1988 p. 2
2. PREPARATION
ALTERN requires two prepared files, held in the current
directory, listing codes for replacement: one for those to
be replaced alternately, another for those to be replaced
globally. Even if you only want to do global replacements,
you must prepare a dummy list of alternate replacements (see
3 a) below). If you want to convert more than one file at a
time, you will also need a file listing the files to be
converted. If your input or output files are to have
non-standard paragraph markers you will need a further file
for each of the two possible markers.
These files must be ASCII text files and can be
prepared with a text editor, such as Wordstar in
Non-Document mode, which can write ASCII files, or by
copying the console output to a file. If you need to handle
strings which include characters that cannot be typed from
the keyboard, use the FILEMAKE utility to create the file or
files which list those strings. Your text editor should be
able to load the resulting files so that you can add further
strings to the lists.
Strings which include double quotation marks (") MUST
NOT be included in the lists, but you can type them in while
running ALTERN.
The prepared lists, and the files to be converted, must
be in the current directory unless you have set a data path
with DPATH or some equivalent utility.
The order of sets of strings in the string-list files
is significant. That feature can be used to achieve complex
or tricky replacements: e.g. you can replace 11/21 by some
special code to print it as a fraction, and then replace 1/2
by another special code, in a single run. Doing it the other
way round will give erroneous output.
Altern v.2.2 documentation (c) C.R.J. Currie 1988 p. 3
3. FORMAT OF STRING-LIST FILES
a) LISTS FOR ALTERNATE REPLACEMENT
Each line should include a string to be replaced and the
first and second replacements. Each string should be
inclosed in double quotation marks and separated by a comma
from the next. The last line of the file should consist of
the word END in upper case. Example:
"CAT","DOG","SHEEP"
",",";","."
END
In this example, all occurrences of CAT in the input file or
files will be replaced alternately by DOG and SHEEP in the
output file or files, and all commas will be replaced
alternately by semicolons and full stops.
If you only want a dummy alternate-replacement file, type
only one line of strings, all of which should be the same.
Example:
"A","A","A"
END
b) LISTS FOR GLOBAL REPLACEMENT
Each line should include a string to be replaced and the
string to replace it. Each string should be inclosed in
double quotation marks and the first should be separated by
a comma from the next. The last line of the file should
consist of the word END in upper case. Example:
"GOAT","ELEPHANT"
"*",","
END
In this example, all occurrences of GOAT in the input file
or files will be replaced by ELEPHANT in the output file or
files, and all asterisks will be replaced by commas.
Altern v.2.2 documentation (c) C.R.J. Currie 1988 p. 4
4. FORMAT OF FILE-LIST FILE
The list of files to be converted should consist simply of
one filespec on each line. Example:
CHUMLEY.TXT
DINGBAT
FILE3.DAT
5. PARAGRAPH MARKER FILES
If your input or output files need a paragraph marker other
than the default, you can put them in two files in the
current directory which MUST be called PARIN and PAROUT
respectively. ALTERN always searches the directory for those
files and only uses the default marker if the relevant file
is missing. The files should consist of the marker code as a
single string inclosed in double quotation marks.
6. RUNNING ALTERN
Simply type ALTERN22 at the DOS command-line prompt and
press the Return key. All answers to prompts within the
program should be terminated by pressing Return. ALTERN will
request the name of the list of input files (if any). If you
only want to process one file, just press Return at that
prompt. ALTERN will then ask you for the filespec of the
single file you wish to process. It will then request
filespecs for the string-list file containing alternate
replacements, and the file containing global replacements.
Press Return after answering each prompt. ALTERN will also
ask you if you wish to check for 8th-bit flags (you should
normally answer Y if the input file is a Wordstar file), and
if you want to type in additional sets of strings for
alternate or global replacement from the keyboard. Answer N
unless you need to replace or insert strings containing
double quotation marks.
ALTERN is not particularly error-friendly, so you should
check your answers to each prompt before pressing Return.
You should be able to reroute console input for the ALTERN
prompts from a DOS text file by typing
ALTERN22 <filename.ext
at the DOS prompt.
Altern v.2.2 documentation (c) C.R.J. Currie 1988 p. 5
7. RUNNING THE FILEMAKE PROGRAM
You only need to use this program if the strings to be
replaced or inserted include characters you can't type into
a text file from the keyboard, e.g. control bytes. You could
use DEBUG instead.
To run the program simply type FILEMAKE at the DOS prompt
and press the return key. The program will ask you for the
name of the string-list file you are creating and whether
you want two strings per line (for GLOBAL replacement) or
three (for ALTERNATE replacment). It will go on prompting
for extra lines until you type 999 as the ASCII code for the
FIRST string in a line. DON'T type 999 in the middle of a
line.
Altern v.2.2 documentation (c) C.R.J. Currie 1988 p. 6
8. LIMITATIONS
Replacement in BINARY files is NOT reliable: ALTERN will
stop processing when 1A hex (^Z) is reached in the input
file.
Maximum size of file which can be processed: half drive
space
Maximum number of files per batch searched: 100
Maximum number of string-sets for alternate replacement: 64
Maximum number of string-sets for global replacement: 64
(You can replace more strings globally if you include them
in the list of alternate replacements with the desired
replacement in both the second and third positions on the
line. That, however, will reduce the number of genuine
alternate replacements you can make.)
Maximum length of individual strings to be replaced or
inserted: 254 bytes
Maximum theoretical length of paragraph in input file: 32767
bytes. In practice it will be considerably less, but
paragraphs of 2k and above have been successfully processed.
The total length of all strings (including lists and input
and output paragraphs) which can be held in memory at once
is probably not more than a 64k block of address space.
No case-independent search.
{continued...}
Altern v.2.2 documentation (c) C.R.J. Currie 1988 p. 7
Nested pairs for alternate replacement: ALTERN treats each
pair separately. That can be significant for typesetting
purposes. Consider the following example, in which the
Wordstar toggles for underline (^S) and bold (^B) are to be
replaced by typesetting codes for italic/non-italic and
bold/normal text.
^SItalic on ^BNow Bold italic ^BNormal italic ^SNormal Roman
The typesetter has no code for 'turn bolding off'; one must
specify normal weight either in Roman or italic, usually the
former. Thus alternate replacement produces
[code for italic]Italic on [code for bold]Now Bold italic
[code for normal Roman]Normal Italic [code for normal Roman]
Normal Roman
so that the phrase 'Normal Italic' is wrongly set in Roman.
There is no way round this problem except to avoid nested
pairs when the file is originally typed, e.g.
^SItalic on^S ^B^SNow bold italic^S^B ^SNormal italic
^SNormal Roman
which will produce the desired result when ALTERN is run
correctly on it.
9. HISTORY
The original version of ALTERN was written in 1986. It
was limited to the alternate replacement of single bytes by
strings and had no provision for global replacement, for
handling codes which could not be typed from the keyboard,
or for altering input and output paragraph markers.
Compiled versions were produced for CP/M, generic
MS-DOS, and the TRS-80 Model III. The source code was
published in NATGUG News.
The program was completely redesigned and rewritten as
version 2.0 in June 1988 and has undergone two major
revisions since.
Altern v.2.2 documentation (c) C.R.J. Currie 1988 p. 8
10. SOFTWARE LICENCE
Copyright (c) 1988 C.R.J. Currie. All Rights Reserved.
You are free to use, copy and distribute ALTERN22 and
FILEMAKE for noncommercial use IF:
NO FEE IS CHARGED FOR USE, COPYING OR DISTRIBUTION.
THE PROGRAMS ARE NOT MODIFIED IN ANY WAY.
Clubs and user groups may charge a nominal fee (less than
$10) for expenses and handling while distributing ALTERN.
This program is provided AS IT IS without any warranty,
expressed or implied, including but not limited to fitness
for a particular purpose.
If you find ALTERN22 useful, a contribution of $10 would be
appreciated.
Send contributions to:
C.R.J. Currie
c.o. Institute of Historical Research
Senate House
Malet Street
London WC1E 7HU
U.K.
